/**
 * Copyright (C) 2008-2025 isoft Infrastructure Software Co., Ltd.
 * SPDX-License-Identifier: LGPL-2.1-only-with-exception
 *
 * This library is free software; you can redistribute it and/or modify it under the terms of the
 * GNU Lesser General Public License as published by the Free Software Foundation; version 2.1.
 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 * You should have received a copy of the GNU Lesser General Public License along with this library;
 * if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 * or see <https://www.gnu.org/licenses/>.
 */
/*
 ************************************************************************************************************************
 **
 **  @file               : StbM.h
 **  @author             : xiongfei.shi
 **  @date               : 2024/12/26
 **  @vendor             : isoft
 **  @description        : The header file for the public interface implementation of the StbM module
 **
 ***********************************************************************************************************************/

/** ===================================================================================================================
 *  REVISION HISTORY
 *  -------------------------------------------------------------------------------------------------------------------
 *  Version   Date       Author         Description
 *  -------------------------------------------------------------------------------------------------------------------
 *  V2.2.0    2024-12-26 xiongfei.shi   1.Refactor and update to R23-11
 *                                      2.Removed offset Time base
 *                                      3.support multi-partition distribution
 *
 ==================================================================================================================== */

/* ================================================ misar justifications ============================================ */
/**
  \page ISOFT_MISRA_Exceptions  MISRA-C:2012 Compliance Exceptions
    ModeName:StbM<br>
  RuleSorce:puhua_rules-2024.12.rcf

    \li VL_StbM_0770
      Reason: design needs
      Risk: No risk.
      Prevention: Functional reliability guaranteed by design.

    \li VL_StbM_4119
      Reason: Intentionally convert float numbers to integer.
      Risk: No risk.
      Prevention: No action required.

    \li VL_StbM_4395
      Reason: Intentionally convert float numbers to unsigned integer.
      Risk: No risk.
      Prevention: No action required.

    \li VL_StbM_1252
      Reason: Intentionally convert suffixed integer constant to a different integral type.
      Risk: No risk.
      Prevention: No action required.

    \li VL_StbM_1259
      Reason: Intentionally convert data type.
      Risk: No risk.
      Prevention: No action required.

    \li VL_StbM_4394
      Reason: essentially unsigned type convert to signed type.
      Risk: No risk.
      Prevention: No action required.

    \li VL_StbM_3673
      Reason: The object addressed by the pointer parameter '%1s' is not modified and so the pointer could be of type
      'pointer to const'. Risk: No risk. Prevention: No action required.

    \li VL_StbM_3414
      Reason: design needs
      Risk: No risk.
      Prevention: Functional reliability guaranteed by design.

    \li VL_StbM_2834
      Reason: The value generated by the configuration tool must be greater than zero during configuration.
      Risk: No risk.
      Prevention: Functional reliability guaranteed by design.

    \li VL_MTR_StbM_STM19
      Reason: In principle, it is not allowed to have multiple exit points for a function, but it helps to improve
      code performance in special circumstances.
      Risk: Increase the difficulty of function debugging.
      Prevention: Full testing to ensure correct functionality.

    \li VL_MTR_StbM_STVAR
      Reason: The total number of variables is related to user configuration, allowing dynamic code to violate this
      under extreme conditions.
      Risk: Code is difficult to maintain.
      Prevention: Design and code review, and have a clear structure and annotated code.

    \li VL_MTR_StbM_STCAL
      Reason: The software architecture is defined according to the AUTOSAR standard.
      Risk: Due to the fan distribution to many functions, understandability and testability can become overly complex.
      Prevention: Design and code review, and have a clear structure and annotated code.

    \li VL_StbM_0533
      Reason: Contains no object or function definitions with external linkage.
      Risk: No risk.
      Prevention: Functional reliability guaranteed by design.

    \li VL_MTR_StbM_CONF
      Reason: Some special files have little or no code, allowing unnecessary comments to be reduced.
      Risk: No risk.
      Prevention: Functional reliability guaranteed by design.
 */

#ifndef STBM_H
#define STBM_H

/* =================================================== inclusions =================================================== */
#include "StbM_Types.h"
#include "SchM_StbM.h"
#if (STBM_ETHTSYN_ENABLE == STD_ON)
#include "Eth_GeneralTypes.h"
#endif
#include "StbM_PBcfg.h"

#ifdef __cplusplus
extern "C" {
#endif

/* =============================================== version information ============================================== */
/* Published Information */
#define STBM_VENDOR_ID                   (62u)
#define STBM_MODULE_ID                   (160u)
#define STBM_INSTANCE_ID                 (0u)
#define STBM_AR_RELEASE_MAJOR_VERSION    (4u)
#define STBM_AR_RELEASE_MINOR_VERSION    (9u)
#define STBM_AR_RELEASE_REVISION_VERSION (0u)
#define STBM_SW_MAJOR_VERSION            (2u)
#define STBM_SW_MINOR_VERSION            (2u)
#define STBM_SW_PATCH_VERSION            (0u)

/* ===================================================== macros ===================================================== */
/*Development errors*/
#define STBM_E_PARAM                 ((uint8)0x0AU)
#define STBM_E_UNINIT                ((uint8)0x0BU)
#define STBM_E_PARAM_POINTER         ((uint8)0x10U)
#define STBM_E_INIT_FAILED           ((uint8)0x11U)
#define STBM_E_SERVICE_NOT_SUPPORTED ((uint8)0x12U)
#define STBM_E_PARAM_TIMESTAMP       ((uint8)0x25U)
#define STBM_E_PARAM_USERDATA        ((uint8)0x26U)
#define STBM_E_INVALID_PARTITION     ((uint8)0xF0U)
#define STBM_E_ALREADY_INITIALIZED   ((uint8)0xF1U)

/*Service ID*/
#define STBM_SID_INIT                       ((uint8)0x00U)
#define STBM_SID_GETVERSIONINFO             ((uint8)0x05U)
#define STBM_SID_GETCURRENTTIME             ((uint8)0x07U)
#define STBM_SID_GETCURRENTVIRTUALLOCALTIME ((uint8)0x1EU)
#define STBM_SID_SETGLOBALTIME              ((uint8)0x0BU)
#define STBM_SID_UPDATEGLOBALTIME           ((uint8)0x10U)
#define STBM_SID_SETUSERDATA                ((uint8)0x0CU)
#define STBM_SID_SETOFFSET                  ((uint8)0x0DU)
#define STBM_SID_GETOFFSET                  ((uint8)0x0EU)
#define STBM_SID_BUSGETCURRENTTIME          ((uint8)0x1FU)
#define STBM_SID_BUSSETGLOBALTIME           ((uint8)0x0FU)
#define STBM_SID_GETRATEDEVIATION           ((uint8)0x11U)
#define STBM_SID_SETRATECORRECTION          ((uint8)0x12U)
#define STBM_SID_GETTIMELEAP                ((uint8)0x13U)
#define STBM_SID_GETTIMEBASESTATUS          ((uint8)0x14U)
#define STBM_SID_STARTTIMER                 ((uint8)0x15U)
#define STBM_SID_GETSYNCTIMERECORDHEAD      ((uint8)0x16U)
#define STBM_SID_GETOFFSETTIMERECORDHEAD    ((uint8)0x17U)
#define STBM_SID_TRIGGERTIMETRANSMISSION    ((uint8)0x1CU)
#define STBM_SID_GETTIMEBASEUPDATECOUNTER   ((uint8)0x1BU)
#define STBM_SID_GETMASTERCONFIG            ((uint8)0x1DU)
#define STBM_SID_MAINFUNCTION               ((uint8)0x04U)

/* ================================================ type definitions ================================================ */
/* Structure which contains additional measurement data */
typedef struct StbM_MeasurementTag
{
    uint32 pathDelay;
#if (STBM_ETHTSYN_ENABLE == STD_ON)
    Eth_RateDeviationType rateDeviation;
#endif
} StbM_MeasurementType;

/* ========================================== internal function definitions ========================================= */

/* =========================================== external data declarations =========================================== */

/* ========================================= external function declarations ========================================= */
/**
 * @brief        Initializes the Synchronized Timebase Manager.
 * @param[in]    configPtr  Pointer to post-build configuration data
 * @reentrant    TRUE (Reentrant for different partitions. Non reentrant for the same partition.)
 * @synchronous  TRUE
 * @trace        CPD-71873
 */
void StbM_Init(const StbM_ConfigType* configPtr);

#if (STBM_VERSIONINFO_API == STD_ON)
/**
 * @brief        This function returns the version information of this module.
 * @param[out]   versioninfo  Pointer to the memory location holding the version information.
 * @reentrant    TRUE
 * @synchronous  TRUE
 * @trace        CPD-71852
 */
void StbM_GetVersionInfo(Std_VersionInfoType* versioninfo);
#endif

/**
 * @brief        Returns a time value(Local Time Base derived from Global Time Base) in standard format.
 * @param[in]    timeBaseId Identification of a Time Base
 * @param[out]   timeTuple  Current time stamp that is valid at this time
 * @param[out]   userData   User data of the Time Base
 * @return       Std_ReturnType
 * @retval       E_OK       Successfully get the Current time
 * @retval       E_NOT_OK   Getting the Current time failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71853
 */
Std_ReturnType StbM_GetCurrentTime(
    StbM_SynchronizedTimeBaseType timeBaseId,
    StbM_TimeTupleType*           timeTuple,
    StbM_UserDataType*            userData);

/**
 * @brief        Returns the Virtual Local Time of the referenced Time Base.
 * @param[in]    timeBaseId   Identification of a Time Base
 * @param[out]   localTimePtr Current Virtual Local Time value
 * @return       Std_ReturnType
 * @retval       E_OK         Successfully get the Virtual Local Time
 * @retval       E_NOT_OK     Getting the Virtual Local Time failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71854
 */
Std_ReturnType
    StbM_GetCurrentVirtualLocalTime(StbM_SynchronizedTimeBaseType timeBaseId, StbM_VirtualLocalTimeType* localTimePtr);

/**
 * @brief        Allows the Customers to set the new global time that has to be valid for the system,
 *               which will be sent to the busses. This function will be used if a Time Master is
 *               present in this ECU.
 * @param[in]    timeBaseId Identification of a Time Base
 * @param[in]    timeStamp  New time stamp
 * @param[in]    userData   New user data(if not NULL)
 * @return       Std_ReturnType
 * @retval       E_OK       Successfully set the global time
 * @retval       E_NOT_OK   Setting the global Time failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71856
 */
Std_ReturnType StbM_SetGlobalTime(
    StbM_SynchronizedTimeBaseType timeBaseId,
    const StbM_TimeStampType*     timeStamp,
    const StbM_UserDataType*      userData);

/**
 * @brief        Allows the Customers to set the Global Time that will be sent to the buses. This
 *               function will be used if a Time Master is present in this ECU. Using UpdateGlobal
 *               Time will not lead to an immediate transmission of the Global Time.
 * @param[in]    timeBaseId Identification of a Time Base
 * @param[in]    timeStamp  New time stamp
 * @param[in]    userData   New user data(if not NULL)
 * @return       Std_ReturnType
 * @retval       E_OK       Successfully update the global time
 * @retval       E_NOT_OK   updating the global Time failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71857
 */
Std_ReturnType StbM_UpdateGlobalTime(
    StbM_SynchronizedTimeBaseType timeBaseId,
    const StbM_TimeStampType*     timeStamp,
    const StbM_UserDataType*      userData);

/**
 * @brief        Allows the customers to set the new user data that has to be valid for the
 *               system, which will be sent to the busses.
 * @param[in]    timeBaseId Identification of a Time Base
 * @param[in]    userData   New user data
 * @return       Std_ReturnType
 * @retval       E_OK       Successfully set the user data
 * @retval       E_NOT_OK   setting the user data failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71858
 */
Std_ReturnType StbM_SetUserData(StbM_SynchronizedTimeBaseType timeBaseId, const StbM_UserDataType* userData);

/**
 * @brief        Allows the Time Base Provider Modules to forward a new Global Time tuple(i.e.,
 *               the Received Time Tuple) to the StbM.
 * @param[in]    timeBaseId     Identification of a Time Base
 * @param[in]    timeTuplePtr   New Global Time Tuple value
 * @param[in]    userDataPtr    New User Data(if not NULL)
 * @param[in]    measureDataPtr New measurement data
 * @return       Std_ReturnType
 * @retval       E_OK           Successfully set Global Time tuple
 * @retval       E_NOT_OK       Setting the Global Time tuple failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71859
 */
Std_ReturnType StbM_BusSetGlobalTime(
    StbM_SynchronizedTimeBaseType timeBaseId,
    const StbM_TimeTupleType*     timeTuplePtr,
    const StbM_UserDataType*      userDataPtr,
    const StbM_MeasurementType*   measureDataPtr);

/**
 * @brief        Returns value of the current rate deviation of a Time Base
 * @param[in]    timeBaseId     Identification of a Time Base
 * @param[out]   rateDeviation  Value of the current rate deviation of a Time Base
 * @return       Std_ReturnType
 * @retval       E_OK           Successfully get rate deviation of a Time Base
 * @retval       E_NOT_OK       Getting the rate deviation failed
 * @reentrant    TRUE
 * @synchronous  TRUE
 * @trace        CPD-71860
 */
Std_ReturnType StbM_GetRateDeviation(StbM_SynchronizedTimeBaseType timeBaseId, StbM_RateDeviationType* rateDeviation);

/**
 * @brief        Allows to set the rate of a Synchronized Time Base(being either a Pure Local Time Base or not)
 * @param[in]    timeBaseId     Identification of a Time Base
 * @param[in]    rateDeviation  value of the applied rate deviation
 * @return       Std_ReturnType
 * @retval       E_OK           Successfully set rate deviation of a Time Base
 * @retval       E_NOT_OK       Setting the rate deviation failed
 * @reentrant    TRUE
 * @synchronous  TRUE
 * @trace        CPD-71861
 */
Std_ReturnType StbM_SetRateCorrection(StbM_SynchronizedTimeBaseType timeBaseId, StbM_RateDeviationType rateDeviation);

/**
 * @brief        Returns value of Time Leap.
 * @param[in]    timeBaseId Identification of a Time Base
 * @param[out]   timeJump   Time leap value
 * @return       Std_ReturnType
 * @retval       E_OK       Successfully get Time leap value
 * @retval       E_NOT_OK   Getting Time leap value failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71862
 */
Std_ReturnType StbM_GetTimeLeap(StbM_SynchronizedTimeBaseType timeBaseId, StbM_TimeDiffType* timeJump);

/**
 * @brief        Returns detailed status information for a Synchronized(or Pure Local) Time Base
 * @param[in]    timeBaseId     Identification of a Time Base
 * @param[out]   timeBaseStatus Status of the Synchronized(or Pure Local) Time Base
 * @return       Std_ReturnType
 * @retval       E_OK           Successfully get status of the Time Base
 * @retval       E_NOT_OK       Getting status of the Time Base failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71863
 */
Std_ReturnType
    StbM_GetTimeBaseStatus(StbM_SynchronizedTimeBaseType timeBaseId, StbM_TimeBaseStatusType* timeBaseStatus);

#if (STBM_NOTIFICATION_CUSTOMER_NUM > 0)
/**
 * @brief        Sets a time value, which the Time Base value is compared against
 * @param[in]    timeBaseId   Identification of a Time Base
 * @param[in]    customerId   The ID of the customer that is being used
 * @param[in]    expireTime   Time value relative to current Time Base value of the Notification
 * @return       Std_ReturnType
 * @retval       E_OK           Successfully start the timer
 * @retval       E_NOT_OK       Starting the timer failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71864
 */
Std_ReturnType StbM_StartTimer(
    StbM_SynchronizedTimeBaseType timeBaseId,
    StbM_CustomerIdType           customerId,
    const StbM_TimeStampType*     expireTime);
#endif

#if (STBM_TIME_RECORDING_SUPPORT == STD_ON)
/**
 * @brief        Accesses to the recorded snapshot data Header of the table belonging to the Synchronized Time Base.
 * @param[in]    timeBaseId            Identification of a Time Base
 * @param[out]   syncRecordTableHead   Header of the table
 * @return       Std_ReturnType
 * @retval       E_OK                  Successful
 * @retval       E_NOT_OK              Failed
 * @reentrant    TRUE
 * @synchronous  TRUE
 * @trace        CPD-71865
 */
Std_ReturnType StbM_GetSyncTimeRecordHead(
    StbM_SynchronizedTimeBaseType timeBaseId,
    StbM_SyncRecordTableHeadType* syncRecordTableHead);
#endif

/**
 * @brief        Called by the <Upper Layer> to force the Timesync Modules to transmit the current
 *               Time Base again due to an incremented timeBaseUpdateCounter[timeBaseId]
 * @param[in]    timeBaseId    Identification of a Time Base
 * @return       Std_ReturnType
 * @retval       E_OK          Successful
 * @retval       E_NOT_OK      Failed
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71866
 */
Std_ReturnType StbM_TriggerTimeTransmission(StbM_SynchronizedTimeBaseType timeBaseId);

/**
 * @brief        Allows the Timesync Modules to detect, whether a Time Base should be
 *               transmitted immediately in the subsequent <Bus>TSyn_MainFunction() cycle.
 * @param[in]    timeBaseId    Identification of a Time Base
 * @return       uint8
 * @retval       Counter value belonging to the Time Base, that indicates a Time Base
 *               update to the Timesync Modules
 * @reentrant    FALSE
 * @synchronous  TRUE
 * @trace        CPD-71867
 */
uint8 StbM_GetTimeBaseUpdateCounter(StbM_SynchronizedTimeBaseType timeBaseId);

#if (STBM_ALLOW_SYSTEM_WIDE_GLOBAL_TIME_MASTER == STD_ON)
/**
 * @brief        Indicates if the functionality for a system wide master(e.g. StbM_SetGlobalTime)
 *               for a given Time Base is available or not.
 * @param[in]    timeBaseId    Identification of a Time Base
 * @param[out]   masterConfig  Indicates, if system wide master functionality is supported
 * @return       Std_ReturnType
 * @retval       E_OK          Successful
 * @retval       E_NOT_OK      Failed
 * @reentrant    TRUE
 * @synchronous  TRUE
 * @trace        CPD-71868
 */
Std_ReturnType StbM_GetMasterConfig(StbM_SynchronizedTimeBaseType timeBaseId, StbM_MasterConfigType* masterConfig);
#endif

#ifdef __cplusplus
}
#endif

#endif
